/**
 * \addtogroup Haptics Haptics API
 * @{  
 *  This file specifies the Samsung Haptics API for Windows Mobile devices.
 *
 *  This haptics API allows the programmer to play haptic notes, or vibrations.
 *  The interface allows the application to play, stop, pause, and resume the
 *  playing note.
 *
 *  The haptics API also provides notification via callbacks when playing stops or ends.
 *  Play can stop or end in any of the following scenarios:
 *  - All the notes specified in SmiHapticsPlayNotes() have been played.
 *  - Play is stopped by calling SmiHapticsStop().
 *  - A previously playing note is stopped by a subsequent call to 
 *       SmiHapticsPlayNotes() with the same handle.
 *
 * Copyright &copy; 2009 Samsung Electronics
 *   
 * File: smiHaptics.h
 */
#ifndef _SMI_HAPTICS_H_
#define _SMI_HAPTICS_H_

#include <smiSDK.h>

/**
Handle to the haptics device.
*/
typedef INT SMI_HAPTICS_HANDLE;

/**
*  Specifies error codes specific to the Haptics API.
*/
typedef enum 
{
    SMI_HAPTICS_ERROR_INVALID_HANDLE   =  SMI_HAPTICS_RESULT_BASE, 
    SMI_HAPTICS_ERROR_OUT_OF_HANDLES   =  SMI_HAPTICS_RESULT_BASE + 1, 
    SMI_HAPTICS_ERROR_INVALID_KEY      =  SMI_HAPTICS_RESULT_BASE + 2 
} SmiHapticsError;

/**
  The state of the haptics device.
*/
typedef enum 
{
	SMI_HAPTICS_STATE_IDLE      , 
	SMI_HAPTICS_STATE_PLAYING   , 
	SMI_HAPTICS_STATE_PAUSED
} SmiHapticsState;

/**
 *  A haptics note style determines how the curve of the playing 
 *  cycle will be formed. 
 */
typedef enum 
{
	SMI_HAPTICS_NOTE_STYLE_STRONG ,  /**<[A sawtooth wave, with no rising curve and a curve on the falling edge of the playing cycle.] */
	SMI_HAPTICS_NOTE_STYLE_SMOOTH ,  /**<[A round wave, with curve on the rising and falling edge of the playing cycle.] */
	SMI_HAPTICS_NOTE_STYLE_SHARP     /**<[A square wave, with no curve on the rising or falling edge of the playing cycle.] */
} SmiHapticsNoteStyle;

/**
 *   The fundamental unit that can be played by the haptics device.   
 */
typedef struct 
{
    BYTE magnitude;            /**<Intensity of the vibration, at its peak.  */ 
    BYTE startingMagnitude;    /**<Starting magnitude. */ 
    BYTE endingMagnitude;      /**<Ending magnitude. */ 
    UINT duration;             /**<Total duration of haptics playing time, in milliseconds. */     
    UINT startTimeDuration;    /**<Start time duration, in milliseconds. */     
    UINT endTimeDuration;      /**<End time duration, in milliseconds. */     
    SmiHapticsNoteStyle style; /**<Note style. */  
    UINT period;               /**<Period, in milliseconds. The range is defined (minPeriod, maxPeriod) in SmiHapticsCapabilities.*/                         
} SmiHapticsNote;

/** 
 *  Specifies the capabilities of the haptics device. 
 */
typedef struct 
{
    UINT maxPeriod;   /**< Maximum period, in milliseconds. */
    UINT minPeriod;   /**< Minimum period, in milliseconds. */

    BOOL startEndMagIsSupported  ; /**< Start/end magnitude support. Supports start/end magnitude if value is 1, otherwise is 0.  */
    BOOL noteStyleIsSupported    ; /**< Note style support. Supports note style if value is 1, otherwise is 0.  */
    BOOL periodicPlayIsSupported ; /**< Periodic play support. Supports periodic play if value is 1, otherwise is 0. */
    BOOL pauseResumeIsSupported  ; /**< Pause/resume support. Supports pause and resume if value is 1, otherwise is 0.  */

} SmiHapticsCapabilities ;

/** 
 *  A callback function pointer type called when playing stops or completes.
 *  Please refer to SmiHapticsPlayNotes() for more details on 
 *  when this callback is called.
 */
typedef void (*SmiHapticsFinishedPlayNotification)(SMI_HAPTICS_HANDLE hapticsHandle, SmiHapticsNote* note);


/**
 *  Sets the license key, if it is required. Some haptics hardware vendors require that 
 *  developers purchase a license from them prior to distributing applications that use 
 *  the Samsung Haptics API to access the haptics component on a Samsung phone.
 *  This provides a way for developers to provide the hardware vendor license key.

 *  If such a license key is not provided, the Samsung Haptics API will display a 
 *  message box when SmiHapticsOpen() is called the first time after the application 
 *  is started.
 *
 *  @param	key [in]			A pointer to the key data.
 *  @param	count [in]			Total byte count for the input key.
 *
 */
SMI_API void SmiHapticsSetKey(const BYTE* key, UINT count);


/**
 *  Opens the haptics device and returns a handle.
 *
 *  @param	handle [out]		A pointer to the haptics device handle.
 *
 *  @return						
 *  							SMI_SUCCESS on success
 *  \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 *  \n							SMI_ERROR_DEVICE_NOT_FOUND if a haptics device is not found
 *  \n							SMI_HAPTICS_ERROR_INVALID_KEY if a valid key is required and missing
 *  \n							SMI_HAPTICS_ERROR_OUT_OF_HANDLES 
 */
SMI_API SMI_RESULT SmiHapticsOpen(SMI_HAPTICS_HANDLE * handle);


/**
 *  Releases resources of the specified handle. 
 *
 *  @param	handle [in]			The haptics device handle. 
 */
SMI_API void SmiHapticsClose(SMI_HAPTICS_HANDLE handle);


/**
 *  Gets the capabilities of the haptics device.
 *
 *  @param	capabilities [out]	A pointer to the capabilities of the device.  
 *
 *  @return                     
 *		                        SMI_SUCCESS on success
 *  \n                          SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 *  \n                          SMI_ERROR_DEVICE_NOT_FOUND if a haptics device is not found             
 */
SMI_API SMI_RESULT SmiHapticsGetCapabilities(SmiHapticsCapabilities *capabilities);


/**
 *  Plays an array of haptics notes for the specified handle.
 *
 *  A handle can be used to play only one haptics note at a time; all previous notes will be 
 *  stopped. When a note has finished playing, the state of its handle will be SMI_HAPTICS_STATE_IDLE.
 *
 *  If \a callback is not NULL, the callback function will be called from the haptics library thread
 * in the following scenarios:
 * - All the notes specified in SmiHapticsPlayNotes() have been played.
 * - Play is stopped by calling SmiHapticsStop().
 * - A previously playing note is stopped by a subsequent call to 
 *       SmiHapticsPlayNotes() with the same handle.
 * - The haptics device is disabled by SmiHapticsDisableDevice() while a 
 *       note is being played.
 *
 *  It is the application's responsibility to allocate and deallocate memory 
 *  associated with \a notes. The application must make sure the memory associated with \a notes  
 *  is valid for the entire time the note is being played. The application can delete the note array pointer in the 
 *  callback function. It is also the application's responsibility to ensure that the \a noteCount parameter and the actual 
 *  number of notes in the \a notes array are equal.  If an element in the \a notes array has an invalid style value, 
 *  SMI_HAPTICS_NOTE_STYLE_SMOOTH will be used.
 *
 *  SmiHapticsPlayNotes() will make the best effort to ensure all notes 
 *  can be played without any jitter between them, but it is not guaranteed.  
 *
 *  @param   handle    [in]		The haptics device handle. 
 *  @param   noteCount [in]		The number of haptics notes in the note array. 
 *  @param   notes     [in]		The haptics note array to be played. 
 *  @param   repeat    [in]		If TRUE, repeat the notes after the notes have 
 *								been played. If repeat is TRUE, play never stops
 *								until SmiHapticsStop() is called.
 *  @param   callback  [in]		The callback function called when play is completed. 
 *
 *  @return                 
 *								SMI_SUCCESS on success
 *  \n							SMI_ERROR_INVALID_PARAMETER if the noteCount parameter is 0 or notes parameter is NULL   
 *  \n							SMI_HAPTICS_ERROR_INVALID_HANDLE if the haptics handle is not valid  
 *  \n							SMI_ERROR_DEVICE_NOT_FOUND if a haptics device is not found             
 */
SMI_API SMI_RESULT  SmiHapticsPlayNotes(SMI_HAPTICS_HANDLE handle, 
                                        UINT noteCount,
                                        const SmiHapticsNote* notes,
                                        BOOL repeat,
                                        SmiHapticsFinishedPlayNotification callback);


/**
 *  Pauses the notes playing on the specified handle.
 *
 *  @param  handle [in]			The haptics device handle
 *
 *  @return             
 *								SMI_SUCCESS on success
 *  \n							SMI_HAPTICS_ERROR_INVALID_HANDLE if the haptics handle is not valid   
 *  \n							SMI_ERROR_DEVICE_NOT_FOUND if a haptics device is not found             
 */
SMI_API SMI_RESULT  SmiHapticsPause(SMI_HAPTICS_HANDLE handle);


/**
 *  Resumes a paused note.
 *
 *  @param  handle [in]			The haptics device handle.
 *
 *  @return             
 *								SMI_SUCCESS on success
 *  \n							SMI_HAPTICS_ERROR_INVALID_HANDLE if the haptics handle is not valid   
 *  \n							SMI_ERROR_DEVICE_NOT_FOUND if a haptics device is not found             
 */
SMI_API SMI_RESULT SmiHapticsResume(SMI_HAPTICS_HANDLE handle);


/**
 *  Stops playing a note.
 *
 *  @param  handle [in]			The haptics device handle.
 */
SMI_API void SmiHapticsStop(SMI_HAPTICS_HANDLE handle);


/**
 *  Gets state of the specified handle.
 *
 *  @param  handle [in]			The haptics device handle.
 *  @param  state  [out]		The state of the haptics device. 
 *
 *  @return             
 *								SMI_SUCCESS on success
 *  \n							SMI_ERROR_INVALID_PARAMETER if the state parameter is NULL  
 *  \n							SMI_HAPTICS_ERROR_INVALID_HANDLE if the haptics handle is not valid   
 *  \n							SMI_ERROR_DEVICE_NOT_FOUND if a haptics device is not found            
 */
SMI_API SMI_RESULT SmiHapticsGetState(SMI_HAPTICS_HANDLE handle,SmiHapticsState * state);

#endif /* _SMI_HAPTICS_H_ */
/* @} */